home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 25 / CU Amiga Magazine's Super CD-ROM 25 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-08].iso / CUCD / Programming / ixemul / sdk / man / cat7 / mdoc.0 < prev    next >
Encoding:
Text File  |  1998-06-15  |  12.3 KB  |  221 lines
  1.  
  2. MDOC(7)                      UNIX Reference Manual                     MDOC(7)
  3.  
  4. NNAAMMEE
  5.      mmddoocc - quick reference guide for the --mmddoocc macro package
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ggrrooffff --mm_d_o_c _f_i_l_e_s _._._.
  9.  
  10. DDEESSCCRRIIPPTTIIOONN
  11.      The --mmddoocc package is a set of content-based and domain-based macros used
  12.      to format the BSD UNIX man pages.  The macro names and their meanings are
  13.      listed below for quick reference; for a detailed explanation on using the
  14.      package, see the tutorial sampler mdoc.samples(7).
  15.  
  16.      The macros are described in two groups, the first includes the structural
  17.      and physical page layout macros.  The second contains the manual and gen-
  18.      eral text domain macros which differentiate the --mmddoocc package from other
  19.      troff formatting packages.
  20.  
  21. PPAAGGEE SSTTRRUUCCTTUURREE DDOOMMAAIINN
  22.    TTiittllee MMaaccrrooss
  23.      To create a valid manual page, these three macros, in this order, are re-
  24.      quired:
  25.      .Dd   _M_o_n_t_h _d_a_y_, _y_e_a_r                       Document date.
  26.      .Dt   _D_O_C_U_M_E_N_T___T_I_T_L_E _[_s_e_c_t_i_o_n_] _[_v_o_l_u_m_e_]     Title, in upper case.
  27.      .Os   _O_P_E_R_A_T_I_N_G___S_Y_S_T_E_M _[_v_e_r_s_i_o_n_/_r_e_l_e_a_s_e_]    Operating system (BSD).
  28.  
  29.    PPaaggee LLaayyoouutt MMaaccrrooss
  30.      Section headers, paragraph breaks, lists and displays.
  31.      .Sh   Section Headers.  Valid headers, in the order of presentation:
  32.            _N_A_M_E           Name section, should include the `.Nm' or `.Fn' and
  33.                           the `.Nd' macros.
  34.            _S_Y_N_O_P_S_I_S       Usage.
  35.            _D_E_S_C_R_I_P_T_I_O_N    General description, should include options and pa-
  36.                           rameters.
  37.            _R_E_T_U_R_N _V_A_L_U_E_S  Sections two and three function calls.
  38.            _E_N_V_I_R_O_N_M_E_N_T    Describe environment variables.
  39.            _F_I_L_E_S          Files associated with the subject.
  40.            _E_X_A_M_P_L_E_S       Examples and suggestions.
  41.            _D_I_A_G_N_O_S_T_I_C_S    Normally used for section four device interface di-
  42.                           agnostics.
  43.            _E_R_R_O_R_S         Sections two and three error and signal handling.
  44.            _S_E_E _A_L_S_O       Cross references and citations.
  45.            _S_T_A_N_D_A_R_D_S      Conformance to standards if applicable.
  46.            _H_I_S_T_O_R_Y        If a standard is not applicable, the history of the
  47.                           subject should be given.
  48.            _B_U_G_S           Gotchas and caveats.
  49.            _o_t_h_e_r          Customized headers may be added at the authors dis-
  50.                           cretion.
  51.      .Ss   Subsection Headers.
  52.      .Pp   Paragraph Break.  Vertical space (one line).
  53.      .D1   (D-one) Display-one Indent and display one text line.
  54.      .Dl   (D-ell) Display-one literal.  Indent and display one line of liter-
  55.            al text.
  56.      .Bd   Begin-display block.  Display options:
  57.            --rraaggggeedd          Unjustified (ragged edges).
  58.            --ffiilllleedd          Justified.
  59.            --lliitteerraall         Literal text or code.
  60.            --ffiillee _n_a_m_e       Read in named _f_i_l_e and display.
  61.            --ooffffsseett _s_t_r_i_n_g   Offset display.  Acceptable _s_t_r_i_n_g values:
  62.                             _l_e_f_t        Align block on left (default).
  63.                             _c_e_n_t_e_r      Approximate center margin.
  64.  
  65.  
  66.                             _i_n_d_e_n_t      Six constant width spaces (a tab).
  67.                             _i_n_d_e_n_t_-_t_w_o  Two tabs.
  68.                             _r_i_g_h_t       Left aligns block 2 inches from right.
  69.                             _x_xnn         Where _x_x is a number from 4nn to 99nn.
  70.                             _A_a          Where _A_a is a callable macro name.
  71.                             _s_t_r_i_n_g      The width of _s_t_r_i_n_g is used.
  72.      .Ed   End-display (matches .Bd).
  73.      .Bl   Begin-list.  Create lists or columns. Options:
  74.            _L_i_s_t_-_t_y_p_e_s
  75.                  --bbuulllleett    Bullet Item List
  76.                  --iitteemm      Unlabeled List
  77.                  --eennuumm      Enumerated List
  78.                  --ttaagg       Tag Labeled List
  79.                  --ddiiaagg      Diagnostic List
  80.                  --hhaanngg      Hanging Labeled List
  81.                  --oohhaanngg     Overhanging Labeled List
  82.                  --iinnsseett     Inset or Run-on Labeled List
  83.            List-parameters
  84.                  --ooffffsseett    (All lists.) See `.Bd' begin-display above.
  85.                  --wwiiddtthh     (--ttaagg and --hhaanngg lists only.)  See `.Bd'.
  86.                  --ccoommppaacctt   (All lists.)  Suppresses blank lines.
  87.      .El   End-list.
  88.      .It   List item.
  89.  
  90. MMAANNUUAALL AANNDD GGEENNEERRAALL TTEEXXTT DDOOMMAAIINN MMAACCRROOSS
  91.      The manual and general text domain macros are special in that most of
  92.      them are parsed for callable macros for example:
  93.  
  94.            .Op Fl s Ar file   Produces [--ss _f_i_l_e]
  95.  
  96.      In this example, the option enclosure macro `.Op' is parsed, and calls
  97.      the callable content macro `Fl' which operates on the argument `s' and
  98.      then calls the callable content macro `Ar' which operates on the argument
  99.      `file'. Some macros may be callable, but are not parsed and vice versa.
  100.      These macros are indicated in the _p_a_r_s_e_d and _c_a_l_l_a_b_l_e columns below.
  101.  
  102.      Unless stated, manual domain macros share a common syntax:
  103.  
  104.            .Va argument [ . , ; : ( ) [ ] argument ... ]
  105.  
  106.      NNoottee: Opening and closing punctuation characters are only recognized as
  107.      such if they are presented one at a time.  The string `),' is not recog-
  108.      nized as punctuation and will be output with a leading white space and in
  109.      what ever font the calling macro uses.  The argument list `] ) ,' is rec-
  110.      ognized as three sequential closing punctuation characters and a leading
  111.      white space is not output between the characters and the previous argu-
  112.      ment (if any).  The special meaning of a punctuation character may be es-
  113.      caped with the string `\&'. For example the following string,
  114.  
  115.            .Ar file1 , file2 , file3 ) .   Produces _f_i_l_e_1, _f_i_l_e_2, _f_i_l_e_3).
  116.  
  117.    MMaannuuaall DDoommaaiinn MMaaccrrooss
  118.      _N_a_m_e    _P_a_r_s_e_d    _C_a_l_l_a_b_l_e     _D_e_s_c_r_i_p_t_i_o_n
  119.      Ad      Yes       Yes          Address. (This macro may be deprecated.)
  120.      Ar      Yes       Yes          Command line argument.
  121.      Cd      No        No           Configuration declaration (section four
  122.                                     only).
  123.      Cm      Yes       Yes          Command line argument modifier.
  124.      Dv      Yes       Yes          Defined variable (source code).
  125.      Er      Yes       Yes          Error number (source code).
  126.      Ev      Yes       Yes          Environment variable.
  127.      Fa      Yes       Yes          Function argument.
  128.      Fd      Yes       Yes          Function declaration.
  129.      Fn      Yes       Yes          Function call (also .Fo and .Fc).
  130.  
  131.  
  132.      Ic      Yes       Yes          Interactive command.
  133.      Li      Yes       Yes          Literal text.
  134.      Nm      Yes       Yes          Command name.
  135.      Op      Yes       Yes          Option (also .Oo and .Oc).
  136.      Ot      Yes       Yes          Old style function type (Fortran only).
  137.      Pa      Yes       Yes          Pathname or file name.
  138.      St      Yes       Yes          Standards (-p1003.2, -p1003.1 or -ansiC)
  139.      Va      Yes       Yes          Variable name.
  140.      Vt      Yes       Yes          Variable type (Fortran only).
  141.      Xr      Yes       Yes          Manual Page Cross Reference.
  142.  
  143.    GGeenneerraall TTeexxtt DDoommaaiinn MMaaccrrooss
  144.      _N_a_m_e    _P_a_r_s_e_d    _C_a_l_l_a_b_l_e     _D_e_s_c_r_i_p_t_i_o_n
  145.      %A      Yes       No           Reference author.
  146.      %B      Yes       Yes          Reference book title.
  147.      %C      No        No           Reference place of publishing (city).
  148.      %D      No        No           Reference date.
  149.      %J      Yes       Yes          Reference journal title.
  150.      %N      No        No           Reference issue number.
  151.      %O      No        No           Reference optional information.
  152.      %P      No        No           Reference page number(s).
  153.      %R      No        No           Reference report Name.
  154.      %T      Yes       Yes          Reference article title.
  155.      %V      No        No           Reference volume.
  156.      Ac      Yes       Yes          Angle close quote.
  157.      Ao      Yes       Yes          Angle open quote.
  158.      Aq      Yes       Yes          Angle quote.
  159.      At      No        No           AT&T UNIX
  160.      Bc      Yes       Yes          Bracket close quote.
  161.      Bf      No        No           Begin font mode.
  162.      Bo      Yes       Yes          Bracket open quote.
  163.      Bq      Yes       Yes          Bracket quote.
  164.      Bx      Yes       Yes          BSD UNIX.
  165.      Db      No        No           Debug (default is "off")
  166.      Dc      Yes       Yes          Double close quote.
  167.      Do      Yes       Yes          Double open quote.
  168.      Dq      Yes       Yes          Double quote.
  169.      Ec      Yes       Yes          Enclose string close quote.
  170.      Ef      No        No           End font mode.
  171.      Em      Yes       Yes          Emphasis (traditional English).
  172.      Eo      Yes       Yes          Enclose string open quote.
  173.      No      Yes       Yes          Normal text (no-op).
  174.      Ns      Yes       Yes          No space.
  175.      Pc      Yes       Yes          Parenthesis close quote.
  176.      Pf      Yes       No           Prefix string.
  177.      Po      Yes       Yes          Parenthesis open quote.
  178.      Pq      Yes       Yes          Parentheses quote.
  179.      Qc      Yes       Yes          Strait Double close quote.
  180.      Ql      Yes       Yes          Quoted literal.
  181.      Qo      Yes       Yes          Strait Double open quote.
  182.      Qq      Yes       Yes          Strait Double quote.
  183.      Re      No        No           Reference start.
  184.      Rs      No        No           Reference start.
  185.      Sc      Yes       Yes          Single close quote.
  186.      So      Yes       Yes          Single open quote.
  187.      Sq      Yes       Yes          Single quote.
  188.      Sm      No        No           Space mode (default is "on")
  189.      Sx      Yes       Yes          Section Cross Reference.
  190.      Sy      Yes       Yes          Symbolic (traditional English).
  191.      Tn      Yes       Yes          Trade or type name (small Caps).
  192.      Ux      Yes       Yes          UNIX
  193.      Xc      Yes       Yes          Extend argument list close.
  194.      Xo      Yes       Yes          Extend argument list close.
  195.  
  196.      Macro names ending in `q' quote remaining items on the argument list.
  197.      Macro names ending in `o' begin a quote which may span more than one line
  198.      of input and are close quoted with the matching macro name ending in `c'.
  199.      Enclosure macros may be nested and are limited to eight arguments.
  200.  
  201.      Note: the extended argument list macros (`.Xo', `.Xc') and the function
  202.      enclosure macros (`.Fo', `.Fc') are irregular.  The extended list macros
  203.      are used when the number of macro arguments would exceed the troff limi-
  204.      tation of nine arguments.
  205.  
  206. CCOONNFFIIGGUURRAATTIIOONN
  207.      For site specific configuration of the macro package, see the file
  208.      _/_u_s_r_/_s_r_c_/_s_h_a_r_e_/_t_m_a_c_/_R_E_A_D_M_E.
  209.  
  210. FFIILLEESS
  211.      tmac.doc          Manual and general text domain macros.
  212.      tmac.doc-common   Common structural macros and definitions.
  213.      tmac.doc-nroff    Site dependent nroff style file.
  214.      tmac.doc-ditroff  Site dependent troff style file.
  215.      tmac.doc-syms     Special defines (such as the standards macro).
  216.  
  217. SSEEEE AALLSSOO
  218.      mdoc.samples(7)
  219.  
  220. BSD Experimental               December 30, 1993                             4
  221.